---
overviewHeaders: [2, 3]
---

# lib.dts

- **类型：**

```ts
type Dts =
  | {
      bundle?: boolean | { bundledPackages?: string[] };
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
      alias?: Record<string, string>;
      tsgo?: boolean;
    }
  | boolean;
```

- **默认值：** `undefined`
- **命令行：** `--dts` / `--no-dts`

配置 TypeScript 声明文件的生成。

## 布尔类型

类型声明文件生成是一个可选功能，你可以设置 `dts: true` 来启用 [bundleless 类型](/guide/advanced/dts#bundleless-类型) 生成。

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: true, // [!code highlight]
    },
  ],
};
```

如果你想要禁用类型声明文件生成，可以设置 `dts: false` 或者不指定 `dts` 选项。

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: false, // [!code highlight]
    },
  ],
};
```

## 对象类型

如果你想要自定义类型声明文件的生成，可以将 `dts` 选项设置为一个对象。

### dts.bundle

- **类型：** `boolean | { bundledPackages?: string[] }`
- **默认值：** `false`

是否打包类型声明文件。

如果你想要 [bundle 类型](/guide/advanced/dts#bundle-类型)，你需要：

1. 安装 [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) 作为开发依赖，它是用于打包类型声明文件的底层工具。

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @microsoft/api-extractor -D" />

2. 将 `dts.bundle` 设置为 `true`。

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        bundle: true,
      },
    },
  ],
};
```

#### dts.bundle.bundledPackages

- **类型：** `string[]`

用于指定需要打包类型声明文件的依赖项，该配置将传递给 `@microsoft/api-extractor` 的 [bundledPackages](https://api-extractor.com/pages/configs/api-extractor_json/#bundledpackages) 配置项。

默认情况下，Rslib 会根据以下配置确定需要外部化的依赖项，详见 [处理第三方依赖](/guide/advanced/third-party-deps)。

- [autoExternal](/config/lib/auto-external) 配置
- [output.externals](/config/rsbuild/output#outputexternals) 配置

那些没有被外部化的直接依赖项（在 `package.json` 中声明）会被添加到 `bundledPackages` 中，这些包的类型声明文件将会被打包到最终的产物中。

当默认行为不能满足需求时，可以通过 `dts.bundle.bundledPackages` 显式指定需要打包的依赖项。设置该配置后，将完全覆盖上述默认行为。

该配置通常用于打包传递依赖项（即直接依赖的依赖）。假设项目直接依赖 `foo`，而 `foo` 又依赖 `bar`，如果需要同时打包 `foo` 和 `bar` 的类型声明文件，可以如下配置：

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        // [!code highlight:3]
        bundle: {
          bundledPackages: ['foo', 'bar'],
        },
      },
    },
  ],
};
```

::: note
`bundledPackages` 可以使用 [minimatch](https://www.npmjs.com/package/minimatch) 语法配置 glob 表达式，但仅会匹配 `package.json` 中已声明的直接依赖项。
:::

### dts.distPath

- **类型：** `string`

类型声明文件的输出目录。

#### 默认值

默认值按照以下优先级确定：

1. 当前 lib 配置中的 `dts.distPath` 值。
2. `tsconfig.json` 文件中的 `declarationDir` 值。
3. 当前 lib 配置中的 [output.distPath](/config/rsbuild/output#outputdistpath) 值或 [output.distPath.root](/config/rsbuild/output#outputdistpath) 值。

#### 示例

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        distPath: './dist-types',
      },
    },
  ],
};
```

### dts.build

- **类型：** `boolean`
- **默认值：** `false`

是否在生成类型声明文件时构建项目的 project references。这相当于在 `tsc` 命令中使用 `--build` 标志。更多详细信息请参考 [项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)。

在配置了 project references 但被引用的项目尚未单独构建时（例如在 monorepo 中直接引用其他项目的源代码，但项目中缺少对应的类型声明文件），需要开启此选项，以确保能够正确生成依赖项目的类型声明，从而保障类型系统的完整性。

::: note

当启用此选项时，你必须在 `tsconfig.json` 中显式设置 `declarationDir` 或 `outDir` 以满足构建要求。

:::

### dts.abortOnError

- **类型：** `boolean`
- **默认值：** `true`

当类型声明文件生成过程中出现错误时，是否中止构建过程。

默认情况下，类型错误会导致构建失败。

当 `abortOnError` 设置为 `false` 时（如下所示），即使代码中存在类型问题，构建仍然会成功。

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        abortOnError: false,
      },
    },
  ],
};
```

::: warning

当禁用该配置时，无法保证类型文件会被正确生成。

:::

### dts.autoExtension

- **类型：** `boolean`
- **默认值：** `false`

是否根据 [format](/config/lib/format) 选项自动设置类型声明文件扩展名。

#### 默认扩展名

当 `dts.autoExtension` 为 `false` 时，类型声明文件扩展名默认为 `.d.ts`。

当 `dts.autoExtension` 设置为 `true` 时，类型声明文件扩展名将会是：

- 当 `package.json` 中设置 `type: module` 时，`esm` 格式使用 `.d.ts`，`cjs` 格式使用 `.d.cts`。

- 当 `package.json` 中设置 `type: commonjs` 或没有 `type` 字段时，`cjs` 格式使用 `.d.ts`，`esm` 格式使用 `.d.mts`。

::: note

1. 这遵循与 [lib.autoExtension](/config/lib/auto-extension) 相同的逻辑，但默认值不同，因为类型声明文件扩展名可能会在不同的模块解析策略中造成一些问题。

2. 类型声明文件的导入路径扩展名重写由 [redirect.dts.extension](/config/lib/redirect#redirectdtsextension) 控制。

3. 当开启 [dts.tsgo](/config/lib/dts#dtstsgo) 时，如果项目同时开启了 [dts.build](/config/lib/dts#dtsbuild) 或者将不同后缀的类型声明文件输出到同一目录，`dts.autoExtension` 无法正常生效。

:::

### dts.alias

- **类型：** `Record<string, string>`
- **默认值：** `{}`

用于配置类型声明文件的路径别名。

`dts.alias` 会与 `tsconfig.json` 中配置的 `compilerOptions.paths` 合并，且 `dts.alias` 具有更高的优先级。

大部分情况下，你不需要使用 `dts.alias`，但当你需要在类型声明文件中使用路径别名却不希望影响 JavaScript 产物时，可以考虑使用它。比如，将 `foo` 的类型声明文件指向 `./compiled/foo`。

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      // [!code highlight:5]
      dts: {
        alias: {
          foo: './compiled/foo',
        },
      },
    },
  ],
};
```

### dts.tsgo

- **类型：** `boolean`
- **默认值：** `false`

是否使用 [tsgo](https://github.com/microsoft/typescript-go) 生成类型声明文件。tsgo 可以提供更快的类型声明文件生成速度，尤其是对于大型项目。

::: tip

此功能目前为**实验性功能**。由于 tsgo 仍处于**实验阶段**，可能会存在一些 bug 以及未解决的问题或限制。因此，在启用该选项前，请确保在你的项目中进行充分测试。

:::

启用该选项，你需要：

1. 安装 [@typescript/native-preview](https://www.npmjs.com/package/@typescript/native-preview) 作为开发依赖。

<PackageManagerTabs command="add @typescript/native-preview -D" />

::: tip 版本要求

`@typescript/native-preview` 要求 Node.js 20.6.0 或更高版本。

:::

2. 在 Rslib 配置文件中设置：

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      dts: {
        tsgo: true, // [!code highlight]
      },
    },
  ],
};
```

3. 为了保证本地开发的一致性，你需要安装对应的 [VS Code 预览版扩展](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.native-preview)，并在 VS Code 设置中添加如下配置：

```json title=".vscode/settings.json"
{
  "typescript.experimental.useTsgo": true
}
```
